2019.3

Itential Automation Platform

On this page:

Log Class

The Log class is an Itential Automation Platform (IAP) class which is used to output errors, warnings, and other information to the console or the IAP log files.

Accessing the Log Object

An instantiation of the Log class is made by IAP on startup. It is exposed as the global log object. IAP applications and adapters may reference the log object.

Example Cog File

The following is an example cog.js file.

/* global adapters */
/* global brokers */
/* global cogs */
/* global log */

...
function test(callback){
log.info("I am a log entry");

...
}

function debug(callback){
log.debug("reconciling:"+device);

...
}

Log Levels

Log levels are used to control the amount of information recorded. Each level has a severity associated with it. The Log class offers several levels of logging.

Method Description
console Deprecated.
spam Collect or output excessive or repetitive messages, large text files, large quantities of data such as search results; information which though relevant would clutter up the log file and render it unusable.
trace Minor events within functions. Like "breadcrumbs" within a function.
debug Major events such as successful data retrieval from an external system or the completion of a function.
info Successful status change; should be limited to one message per successful action.
warn Issues or unexpected behavior which does not impact functionality.
error Errors or failures in the code which impacts functionality.

Note: console.log should not be used as it is not supported by IAP. The best practice is to use the log class.

Log levels are defined in the loggerProps object of the properties.json file in the IAP root directory.

  • The log_level property determines the level for the log file.
  • The console_level property determines the level for the console.
  • In the properties.json example below, the log_level is set to info, which means any logging that has an equal or higher severity value than info will be written to /var/log/pronghorn/pronghorn.log (info, warn, error, debug, console, trace).
    • If the log_level were debug, IAP would monitor all log.debug messages through cogs and adapters and log that information.

Properties File

The following is an example of the loggerProps object of a properties.json file.

...
"loggerProps": {
"description": "Logging",
"log_max_files": 100,
"log_max_file_size": 1048576,
"log_level": "info",
"log_directory": "/var/log/itential/",
"log_filename": "itential.log",
"log_timezone_offset": 0,
"console_level": "info"
},
...

Changing Log Levels in IAP

An administrator can modify the log_level in IAP using the Server Profile Manager interface by navigating to: Settings > Profiles > loggerProps.

Logging Properties

As an example, to change the log_level to debug:

  • Replace the value of the log_level property by changing info to debug.
  • Click SAVE (upper-right corner).

Of note, the specific details logged at each level (i.e., what information is logged and what messages are returned) is determined by the application developer and defined within the cog and adapter code.

Logging Profile